home *** CD-ROM | disk | FTP | other *** search
/ Night Owl 6 / Night Owl's Shareware - PDSI-006 - Night Owl Corp (1990).iso / 039a / oopbas.zip / OOPBASE.DOC < prev    next >
Text File  |  1991-08-22  |  10KB  |  427 lines
  1.  
  2. --------------------------------------------------------------------------
  3.     oopbase.doc
  4.  
  5.     OOP Database routines
  6.  
  7.     Interface Documentation
  8.  
  9.         Silico-Magnetic Intelligence
  10.     24 Jean Lane
  11.     Chestnut Ridge, NY 10952
  12.     914 426-2610   FAX: 914 426-3152
  13.  
  14.  
  15.  
  16. --------------------------------------------------------------------------
  17.  
  18. Summary
  19.  
  20. The oopbase module is an object-oriented database library.
  21. A record in the database consists of a key and a data part.
  22. The two parts are separated by an internal character in the database.
  23. The records are organized into a multi-level tree following ascii
  24. sorting sequence. The combined size of key and data cannot exceed
  25. Record_max which is defined in oopbase.d.
  26.  
  27.  
  28. List of Functions
  29.  
  30.         db_start         - activate module
  31.  
  32.     db_end            - deactivate module
  33.  
  34.     db_open             - activate database object
  35.  
  36.     db_close            - destroy database object
  37.  
  38.         db_create           - create database
  39.  
  40.     db_insert           - add a record
  41.  
  42.     db_read_key         - read database by key
  43.  
  44.     db_search           - search database
  45.  
  46.     db_go_to_first     - set database pointer to beginning
  47.  
  48.     db_go_to_last      - set database pointer to end
  49.  
  50.     db_read_next             - read next record
  51.  
  52.     db_read_previous         - read_previous record
  53.  
  54.  
  55. Notes
  56.  
  57.  
  58.  
  59. --------------------------------------------------------------------------
  60.  db_open
  61. --------------------------------------------------------------------------
  62.  
  63.  Function       Creates a database object.
  64.  
  65.  Syntax         int db_open( char * file_name )
  66.  
  67.  Arguments      file_name - disk name of database
  68.  
  69.  Remarks        If creation succesful, memory is allocated for object,
  70.             file is opened, and a handle is returned.
  71.  
  72.  
  73.  Return value   >=0 ok, handle is returned
  74.                 Eof failed to create object
  75.  Limitations
  76.  
  77.  See also       db_close, db_create
  78.  
  79.  Example        if ( ( phone_base = db_open( "phones.db") ) == Eof )
  80.           ret = false;
  81.  
  82.  
  83. --------------------------------------------------------------------------
  84.  db_close
  85. --------------------------------------------------------------------------
  86.  
  87.  Function        Destroys object.
  88.  
  89.  Syntax          void db_close ( int handle)
  90.  
  91.  Arguments       handle - handle of object to be destroyed
  92.  
  93.  
  94.  
  95.  Remarks         Closes file, deallocates memory, releases handle.
  96.  
  97.  Limitations
  98.  
  99.  See also        db_open
  100.  
  101.  Example         db_close( phone_base );
  102.  
  103.  
  104.  
  105.  
  106. --------------------------------------------------------------------------
  107.  db_start
  108. --------------------------------------------------------------------------
  109.  
  110.  Function       Allocates memory for module structure.
  111.  
  112.  Syntax         int db_start()
  113.  
  114.  Arguments
  115.  
  116.  
  117.  
  118.  Remarks        Should be called at the beginning of the program.
  119.  
  120.  
  121.  
  122.  Return value   true:  allocation is ok, module can be used
  123.                 false: failure to allocate, module is not active
  124.  
  125.  Limitations
  126.  
  127.  See also       db_end
  128.  
  129.  Example        if ( not db_start() )
  130.           ret = Eof;
  131.  
  132.  
  133. --------------------------------------------------------------------------
  134.  db_end
  135. --------------------------------------------------------------------------
  136.  
  137.  Function       Deallocates memory of module structure.
  138.  
  139.  Syntax         void db_end()
  140.  
  141.  Arguments
  142.  
  143.  
  144.  Remarks        Should be called at the end of the program.
  145.  
  146.  
  147.  Return value
  148.  
  149.  Limitations
  150.  
  151.  See also       db_start
  152.  
  153.  Example        db_end();
  154.  
  155.  
  156.  
  157. --------------------------------------------------------------------------
  158.  db_create
  159. --------------------------------------------------------------------------
  160.  
  161.  Function       Create database
  162.  
  163.  Syntax         int db_create( char *file_name, char *database_title)
  164.  
  165.  
  166.  Arguments     file_name  - database diskfile name
  167.         database_title  - diskfile header information
  168.  
  169.  
  170.  Remarks        Creates a new database.
  171.         Use it only once!
  172.         Open must be used to access the created database.
  173.  
  174.  
  175.  Return value   true  - db created ok
  176.                 false - io failure
  177.  
  178.  Limitations
  179.  
  180.  See also       db_open
  181.  
  182.  Example          db_create( "phones.db", "Customer telephone numbers");
  183.  
  184.  
  185.  
  186. --------------------------------------------------------------------------
  187.  db_insert
  188. --------------------------------------------------------------------------
  189.  
  190.  Function       Insert record
  191.  
  192.  Syntax         int db_insert( int handle, char *key, char *data)
  193.  
  194.  
  195.  Arguments      key - key string
  196.         data - data string
  197.  
  198.  
  199.  Remarks        Inserts new record into database.
  200.         Combined size cannot exceed Record_max default.
  201.  
  202.  
  203.  Return value   Eof      - io failure
  204.                 false    - duplicate
  205.         true     - inserted ok
  206.  Limitations
  207.  
  208.  See also
  209.  
  210.  Example      db_insert( phone_base, "Jane Gizzy", "212 543-2344");
  211.  
  212.  
  213. --------------------------------------------------------------------------
  214.  db_update
  215. --------------------------------------------------------------------------
  216.  
  217.  Function       Update record
  218.  
  219.  Syntax         int db_update( int handle, char *key, char *new_data)
  220.  
  221.  
  222.  Arguments      key of current record
  223.         new_data to replace current data
  224.  
  225.  
  226.  
  227.  Remarks        Updates record with key by replacing current data with
  228.         new data.
  229.         If record does not exist, it is inserted.
  230.  
  231.  
  232.  
  233.  Return value   true    - ok
  234.                 false   - io failure
  235.  
  236.  Limitations
  237.  
  238.  See also       db_insert
  239.  
  240.  Example      db_update( phone_base, "Jane Gizzy", "202 345-7777");
  241.  
  242.  
  243.  
  244. --------------------------------------------------------------------------
  245.  db_delete
  246. --------------------------------------------------------------------------
  247.  
  248.  Function       Delete record
  249.  
  250.  Syntax         int db_delete( int handle, char *key)
  251.  
  252.  
  253.  Arguments      key - key of record to be deleted
  254.  
  255.  
  256.  Remarks        Deletes record from database.
  257.  
  258.  
  259.  Return value   Eof      - io failure
  260.                 false    - not found
  261.         true     - record deleted
  262.  Limitations
  263.  
  264.  See also       db_search
  265.  
  266.  Example      db_delete( phone_base, "Jane Gizzy");
  267.  
  268.  
  269.  
  270. --------------------------------------------------------------------------
  271.  db_go_to_first
  272. --------------------------------------------------------------------------
  273.  
  274.  Function       Position to head of database
  275.  
  276.  Syntax         void db_go_to_first( int handle)
  277.  
  278.  
  279.  Remarks        Positions to first record in ascii ascending sort order.
  280.  
  281.  
  282.  Limitations
  283.  
  284.  See also       db_read_next
  285.  
  286.  Example     db_go_to_first( phone_base);
  287.  
  288.  
  289.  
  290. --------------------------------------------------------------------------
  291.  db_go_to_last
  292. --------------------------------------------------------------------------
  293.  
  294.  Function       Position to end of database
  295.  
  296.  Syntax         void db_go_to_last( int handle)
  297.  
  298.  
  299.  Remarks        Positions to last record in ascii ascending order.
  300.  
  301.  
  302.  Limitations
  303.  
  304.  See also       db_read_previous
  305.  
  306.  Example        db_go_to_last (phone_base);
  307.  
  308.  
  309.  
  310. --------------------------------------------------------------------------
  311.  db_read_next
  312. --------------------------------------------------------------------------
  313.  
  314.  Function       Read next record
  315.  
  316.  Syntax         int db_read_next( int handle, char *key, char *data)
  317.  
  318.  
  319.  Arguments      key  - key of next record
  320.         data - data of next record
  321.  
  322.  
  323.  Remarks        Reads next record in database.
  324.         Returns record key and data.
  325.  
  326.  
  327.  
  328.  
  329.  Return value   Eof    - if at end of database
  330.                 true   - otherwise
  331.  
  332.  Limitations
  333.  
  334.  See also       db_go_to_first
  335.  
  336.  Example      while ( db_read_next(phone_base, name, phone) EQ true)
  337.           printf("\n %s \t-- %s", name, phone);
  338.  
  339.  
  340.  
  341. --------------------------------------------------------------------------
  342.  db_read_previous
  343. --------------------------------------------------------------------------
  344.  
  345.  Function       Read previous record
  346.  
  347.  Syntax         int db_read_previous( int handle, char *key, char *data)
  348.  
  349.  
  350.  Arguments      key  - key of next record
  351.         data - data of next record
  352.  
  353.  
  354.  Remarks        Reads previous record in database.
  355.         Returns record key and data.
  356.  
  357.  
  358.  Return value   Eof    - if at head of database
  359.                 true   - otherwise
  360.  
  361.  Limitations
  362.  
  363.  See also       db_go_to_last
  364.  
  365.  Example      while ( db_read_previous(phone_base, name, phone) EQ true)
  366.           printf("\n %s \t-- %s", name, phone);
  367.  
  368.  
  369.  
  370. --------------------------------------------------------------------------
  371.  db_read_key
  372. --------------------------------------------------------------------------
  373.  
  374.  Function       Read key
  375.  
  376.  Syntax         int db_read_key( int handle, char *key, char *data)
  377.  
  378.  
  379.  Arguments      key  - key of record to be located
  380.         data - data of located record
  381.  
  382.  
  383.  
  384.  Remarks        Locates record with key as identifier.
  385.         Returns record data.
  386.  
  387.  
  388.  
  389.  
  390.  Return value   true    - ok
  391.                 false   - not found
  392.  
  393.  Limitations
  394.  
  395.  See also       db_search
  396.  
  397.  Example         db_read_key( phone_base, "Jane Gizzy", phone);
  398.  
  399.  
  400.  
  401. --------------------------------------------------------------------------
  402.  db_search_key
  403. --------------------------------------------------------------------------
  404.  
  405.  Function       Search key
  406.  
  407.  Syntax         int db_search_key( int handle, char *key)
  408.  
  409.  
  410.  Arguments      key  - record sought
  411.  
  412.  Remarks        Searches database for record with key.
  413.  
  414.  
  415.  Return value   true   - record found
  416.                 false  - not found
  417.  
  418.  Limitations
  419.  
  420.  See also       db_read_next, db_read_previous
  421.  
  422.  Example        if ( db_search( phone_base, "Jane Gizzy") EQ true)
  423.         begin_if ....... end_if
  424.  
  425.  
  426.      End of oopbase Interface Documentation
  427.